feat: cohort CSV sync endpoint and cohort summary on segments - #8294

Walkthrough

Adds multipart CSV synchronisation for cohorts. The change validates CSV size and content, extracts identifiers, updates memberships in batches, tracks ignored rows, increments cohort versions, and queues delta application. Cohort creation now accepts and persists metadata. Segment responses expose related cohort details. The change adds metrics, event catalogue entries, tests, and OpenAPI schemas.

Estimated code review effort: 4 (Complex) | ~60 minutes

Merge Risk: 🟠 High · up to aa61a

The CSV synchronization feature can strand membership updates, accept identifiers that downstream processing cannot handle, or leave external membership state inconsistent with the database under concurrent sync and application. These correctness and data-integrity risks make the PR unsafe to merge until the synchronization and validation paths are fixed.

• X
• Mastodon
• Reddit
• LinkedIn

Playwright Test Results (private-cloud - depot-ubuntu-latest-16)

 1 passed

Details

 1 test across 1 suite
 54.8 seconds
 9fbfb13
 🔄 Run: #19704 (attempt 1)

• CSV sync endpoint (cohorts/views.py, cohorts/services.py) - New POST .../cohorts/{id}/sync-csv/ action with multipart upload; parses the CSV, computes a membership delta against existing rows, creates/updates/deletes CohortMembership rows inside a locked transaction, bumps the cohort version, and enqueues the applier task.
• CSV extraction (cohorts/services.py) - extract_identifiers_from_csv handles BOM stripping, configurable identifier column, header skipping, deduplication, empty/too-long filtering, and wraps csv.Error into a ValidationError.
• Serializer & validation (cohorts/serializers.py) - CohortCsvSyncSerializer validates the uploaded file against the 10 MB size cap; CohortSerializer now accepts optional metadata on create and validates required metadata fields against the managed segment's content type.
• Cohort summary on segments (segments/serializers.py, segments/views.py) - SegmentSerializer gains a read-only cohort field via SerializerMethodField, backed by a prefetch on the list queryset. _SegmentCohortSerializer exposes id, environment, source_type, version, and deletion_requested_at.
• Observability (cohorts/metrics.py, docs) - New flagsmith_cohorts_csv_syncs_total counter and flagsmith_cohorts_csv_sync_identifiers histogram; cohorts.csv.synced structured log event. Docs catalogues updated with new entries and corrected line numbers.
• OpenAPI / MCP spec - openapi.yaml and mcp/openapi.json updated with the new endpoint, _SegmentCohort schema, SourceTypeEnum, and the cohort field on segment schemas.

1. Run the new unit tests: pytest api/tests/unit/cohorts/test_services.py api/tests/unit/cohorts/test_views.py api/tests/unit/segments/test_unit_segments_views.py -k "csv or cohort".
2. POST a multipart CSV to /api/v1/environments/{key}/cohorts/{id}/sync-csv/ and confirm a 202 with correct added/removed/unchanged/ignored counts.
3. Re-upload a different CSV to the same cohort and verify the delta: removed identifiers move to pending_remove, new ones appear as pending_add, and the version increments.
4. GET /api/v1/projects/{id}/segments/ and confirm each cohort-managed segment includes a cohort summary with source_type, version, and deletion_requested_at; non-cohort segments return cohort: null.
5. Verify permissions: a user with only VIEW_ENVIRONMENT (no MANAGE_SEGMENTS) receives 403 on sync-csv.

• The task processor stores tasks in the database, so .delay() inside transaction.atomic() is transaction-safe (task becomes visible only after commit). This is consistent with usage across the codebase but could not be verified against the task processor source in this environment.
• SoftDeleteExportableModel's default manager filters out records with deleted_at IS NOT NULL, so segment.cohorts.all() correctly excludes fully deleted cohorts while including those pending drain.

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.